From 0dd93537b309d7962938bce6143f7645e5915592 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Javier=20Jard=C3=B3n?= Date: Thu, 14 Apr 2011 22:07:29 +0100 Subject: [PATCH] Move documentation to inline comments: GtkIconTheme --- docs/reference/gtk/tmpl/.gitignore | 1 + docs/reference/gtk/tmpl/gtkicontheme.sgml | 502 ---------------------- gtk/gtkicontheme.c | 86 ++++ gtk/gtkicontheme.h | 22 + 4 files changed, 109 insertions(+), 502 deletions(-) delete mode 100644 docs/reference/gtk/tmpl/gtkicontheme.sgml diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore index 6ad4cb70bd..8c5ba90135 100644 --- a/docs/reference/gtk/tmpl/.gitignore +++ b/docs/reference/gtk/tmpl/.gitignore @@ -53,6 +53,7 @@ gtkhscale.sgml gtkhscrollbar.sgml gtkhseparator.sgml gtkiconfactory.sgml +gtkicontheme.sgml gtkiconview.sgml gtkimagemenuitem.sgml gtkimcontext.sgml diff --git a/docs/reference/gtk/tmpl/gtkicontheme.sgml b/docs/reference/gtk/tmpl/gtkicontheme.sgml deleted file mode 100644 index 0bcae211fa..0000000000 --- a/docs/reference/gtk/tmpl/gtkicontheme.sgml +++ /dev/null @@ -1,502 +0,0 @@ - -GtkIconTheme - - -Looking up icons by name - - - -#GtkIconTheme provides a facility for looking up icons by name -and size. The main reason for using a name rather than simply -providing a filename is to allow different icons to be used -depending on what icon theme is selected -by the user. The operation of icon themes on Linux and Unix -follows the Icon -Theme Specification. There is a default icon theme, -named hicolor where applications should install -their icons, but more additional application themes can be -installed as operating system vendors and users choose. - - -Named icons are similar to the -facility, and the distinction between the two may be a bit confusing. -A few things to keep in mind: - - - - -Stock images usually are used in conjunction with -., such as %GTK_STOCK_OK or -%GTK_STOCK_OPEN. Named icons are easier to set up and therefore -are more useful for new icons that an application wants to -add, such as application icons or window icons. - - - - -Stock images can only be loaded at the symbolic sizes defined -by the #GtkIconSize enumeration, or by custom sizes defined -by gtk_icon_size_register(), while named icons are more flexible -and any pixel size can be specified. - - - - -Because stock images are closely tied to stock items, and thus -to actions in the user interface, stock images may come in -multiple variants for different widget states or writing -directions. - - - - -A good rule of thumb is that if there is a stock image for what -you want to use, use it, otherwise use a named icon. It turns -out that internally stock images are generally defined in -terms of one or more named icons. (An example of the -more than one case is icons that depend on writing direction; -GTK_STOCK_GO_FORWARD uses the two themed icons -"gtk-stock-go-forward-ltr" and "gtk-stock-go-forward-rtl".) - - -In many cases, named themes are used indirectly, via #GtkImage -or stock items, rather than directly, but looking up icons -directly is also simple. The #GtkIconTheme object acts -as a database of all the icons in the current theme. You -can create new #GtkIconTheme objects, but its much more -efficient to use the standard icon theme for the #GdkScreen -so that the icon information is shared with other people -looking up icons. In the case where the default screen is -being used, looking up an icon can be as simple as: - - - -GError *error = NULL; -GtkIconTheme *icon_theme; -GdkPixbuf *pixbuf; - -icon_theme = gtk_icon_theme_get_default (); -pixbuf = gtk_icon_theme_load_icon (icon_theme, - "my-icon-name", /* icon name */ - 48, /* size */ - 0, /* flags */ - &error); -if (!pixbuf) - { - g_warning ("Couldn't load icon: %s", error->message); - g_error_free (error); - } -else - { - /* Use the pixbuf */ - g_object_unref (pixbuf); - } - - - - - - - - - - - - - - - - -Contains information found when looking up an icon in -an icon theme. - - - - - -Acts as a database of information about an icon theme. -Normally, you retrieve the icon theme for a particular -screen using gtk_icon_theme_get_for_screen() and it -will contain information about current icon theme for -that screen, but you can also create a new #GtkIconTheme -object and set the icon theme name explicitely using -gtk_icon_theme_set_custom_theme(). - - - - - - - - -@icontheme: the object which received the signal. - - - - - - -@GTK_ICON_LOOKUP_NO_SVG: -@GTK_ICON_LOOKUP_FORCE_SVG: -@GTK_ICON_LOOKUP_USE_BUILTIN: -@GTK_ICON_LOOKUP_GENERIC_FALLBACK: -@GTK_ICON_LOOKUP_FORCE_SIZE: - - - -The #GQuark used for #GtkIconThemeError errors. - - - - - - - - - -@GTK_ICON_THEME_NOT_FOUND: -@GTK_ICON_THEME_FAILED: - - - - - - -@void: -@Returns: - - - - - - - -@void: -@Returns: - - - - - - - -@screen: -@Returns: - - - - - - - -@icon_theme: -@screen: - - - - - - - -@icon_theme: -@path: -@n_elements: - - - - - - - -@icon_theme: -@path: -@n_elements: - - - - - - - -@icon_theme: -@path: - - - - - - - -@icon_theme: -@path: - - - - - - - -@icon_theme: -@theme_name: - - - - - - - -@icon_theme: -@icon_name: -@Returns: - - - - - - - -@icon_theme: -@icon_name: -@size: -@flags: -@Returns: - - - - - - - -@icon_theme: -@icon_names: -@size: -@flags: -@Returns: - - - - - - - -@icon_theme: -@icon: -@size: -@flags: -@Returns: - - - - - - - -@icon_theme: -@icon_name: -@size: -@flags: -@error: -@Returns: - - - - - - - -@icon_theme: -@Returns: - - - - - - - -@icon_theme: -@context: -@Returns: - - - - - - - -@icon_theme: -@icon_name: -@Returns: - - - - - - - -@icon_theme: -@Returns: - - - - - - - -@icon_theme: -@Returns: - - - - - - - -@icon_name: -@size: -@pixbuf: - - - - - - - -@icon_info: -@Returns: - - - - - - - -@icon_info: - - - - - - - -@icon_theme: -@pixbuf: -@Returns: - - - - - - - -@icon_info: -@Returns: - - - - - - - -@icon_info: -@Returns: - - - - - - - -@icon_info: -@Returns: - - - - - - - -@icon_info: -@error: -@Returns: - - - - - - - -@icon_info: -@fg: -@success_color: -@warning_color: -@error_color: -@was_symbolic: -@error: -@Returns: - - - - - - - -@icon_info: -@style: -@state: -@was_symbolic: -@error: -@Returns: - - - - - - - -@icon_info: -@context: -@was_symbolic: -@error: -@Returns: - - - - - - - -@icon_info: -@raw_coordinates: - - - - - - - -@icon_info: -@rectangle: -@Returns: - - - - - - - -@icon_info: -@points: -@n_points: -@Returns: - - - - - - - -@icon_info: -@Returns: - - diff --git a/gtk/gtkicontheme.c b/gtk/gtkicontheme.c index db65d5171e..1845adb5ae 100644 --- a/gtk/gtkicontheme.c +++ b/gtk/gtkicontheme.c @@ -49,6 +49,92 @@ #include "gtksettings.h" #include "gtkprivate.h" + +/** + * SECTION:gtkicontheme + * @Short_description: Looking up icons by name + * @Title: GtkIconTheme + * + * #GtkIconTheme provides a facility for looking up icons by name + * and size. The main reason for using a name rather than simply + * providing a filename is to allow different icons to be used + * depending on what icon theme is selected + * by the user. The operation of icon themes on Linux and Unix + * follows the Icon + * Theme Specification. There is a default icon theme, + * named hicolor where applications should install + * their icons, but more additional application themes can be + * installed as operating system vendors and users choose. + * + * Named icons are similar to the + * facility, and the distinction between the two may be a bit confusing. + * A few things to keep in mind: + * + * + * Stock images usually are used in conjunction with + * , such as %GTK_STOCK_OK or + * %GTK_STOCK_OPEN. Named icons are easier to set up and therefore + * are more useful for new icons that an application wants to + * add, such as application icons or window icons. + * + * + * Stock images can only be loaded at the symbolic sizes defined + * by the #GtkIconSize enumeration, or by custom sizes defined + * by gtk_icon_size_register(), while named icons are more flexible + * and any pixel size can be specified. + * + * + * Because stock images are closely tied to stock items, and thus + * to actions in the user interface, stock images may come in + * multiple variants for different widget states or writing + * directions. + * + * + * A good rule of thumb is that if there is a stock image for what + * you want to use, use it, otherwise use a named icon. It turns + * out that internally stock images are generally defined in + * terms of one or more named icons. (An example of the + * more than one case is icons that depend on writing direction; + * %GTK_STOCK_GO_FORWARD uses the two themed icons + * "gtk-stock-go-forward-ltr" and "gtk-stock-go-forward-rtl".) + * + * In many cases, named themes are used indirectly, via #GtkImage + * or stock items, rather than directly, but looking up icons + * directly is also simple. The #GtkIconTheme object acts + * as a database of all the icons in the current theme. You + * can create new #GtkIconTheme objects, but its much more + * efficient to use the standard icon theme for the #GdkScreen + * so that the icon information is shared with other people + * looking up icons. In the case where the default screen is + * being used, looking up an icon can be as simple as: + * + * + * GError *error = NULL; + * GtkIconTheme *icon_theme; + * GdkPixbuf *pixbuf; + * + * icon_theme = gtk_icon_theme_get_default (); + * pixbuf = gtk_icon_theme_load_icon (icon_theme, + * "my-icon-name", // icon name + * 48, // size + * 0, // flags + * &error); + * if (!pixbuf) + * { + * g_warning ("Couldn't load icon: %s", error->message); + * g_error_free (error); + * } + * else + * { + * // Use the pixbuf + * g_object_unref (pixbuf); + * } + * + * + */ + + #define DEFAULT_THEME_NAME "hicolor" typedef enum diff --git a/gtk/gtkicontheme.h b/gtk/gtkicontheme.h index 607bdf09e4..6d3ea2d266 100644 --- a/gtk/gtkicontheme.h +++ b/gtk/gtkicontheme.h @@ -40,11 +40,28 @@ G_BEGIN_DECLS #define GTK_IS_ICON_THEME_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), GTK_TYPE_ICON_THEME)) #define GTK_ICON_THEME_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), GTK_TYPE_ICON_THEME, GtkIconThemeClass)) +/** + * GtkIconInfo: + * + * Contains information found when looking up an icon in + * an icon theme. + */ typedef struct _GtkIconInfo GtkIconInfo; typedef struct _GtkIconTheme GtkIconTheme; typedef struct _GtkIconThemeClass GtkIconThemeClass; typedef struct _GtkIconThemePrivate GtkIconThemePrivate; +/** + * GtkIconTheme: + * + * Acts as a database of information about an icon theme. + * Normally, you retrieve the icon theme for a particular + * screen using gtk_icon_theme_get_for_screen() and it + * will contain information about current icon theme for + * that screen, but you can also create a new #GtkIconTheme + * object and set the icon theme name explicitely using + * gtk_icon_theme_set_custom_theme(). + */ struct _GtkIconTheme { /*< private >*/ @@ -94,6 +111,11 @@ typedef enum GTK_ICON_LOOKUP_FORCE_SIZE = 1 << 4 } GtkIconLookupFlags; +/** + * GTK_ICON_THEME_ERROR: + * + * The #GQuark used for #GtkIconThemeError errors. + */ #define GTK_ICON_THEME_ERROR gtk_icon_theme_error_quark () /** -- 2.30.2